Skip to content

build(webp): upgrade the codec from libwebp ~1.1.x to v1.6.0 - #114

Open
ckellet wants to merge 2 commits into
jamsinclair:mainfrom
ckellet:up/webp-libwebp-1.6.0
Open

ckellet wants to merge 2 commits into
jamsinclair:mainfrom
ckellet:up/webp-libwebp-1.6.0

Conversation

@ckellet

@ckellet ckellet commented Sep 2, 2026

Copy link
Copy Markdown

Closes #112.

packages/webp was still compiling libwebp from a November 2020 commit hash. The shipped webp_enc.wasm reported version() 0x010100; it now reports 0x010600. Two commits: the codec bump, then the qmin/qmax binding the issue asks for in step 6.

Against the issue's checklist

# Item
1 Pin a release tarball, not a SHA CODEC_VERSION = 1.6.0 + refs/tags/v$(CODEC_VERSION).tar.gz
2 Rebuild encoder, SIMD encoder, decoder all three, version() 0x010100 → 0x010600
3 Link libsharpyuv explicit dependency for both encoder builds, ordered after libwebp.a; the decoder never pulls those symbols in
4 CMake flags / threads -DWEBP_USE_THREAD=0 replaces -DCMAKE_DISABLE_FIND_PACKAGE_Threads=1 — see below
5 Emscripten version 2.0.34 → 4.0.16, pinned per-codec in packages/webp/codec/package.json
6 Bind qmin/qmax, resolve thread_level second commit
7 README versions all three set to v1.6.0
8 Smoke version() checked, lossy/lossless/sharp-YUV round-trips compared against the old modules, plus a new integration test

Two things the issue didn't anticipate

AVX2. 1.6.0 added AVX2 lossless paths. They don't compile under Emscripten — the sources pass __m256i* into intrinsics Emscripten declares as taking __m256i_u* — and even if they did, Emscripten emulates 256-bit intrinsics as pairs of 128-bit wasm SIMD ops, so they'd cost binary size without buying throughput. Masked off with -U__AVX2__.

SSE2 goes with it. Masking AVX2 isn't enough on its own. cpu.cmake stops probing at the third entry of its extension list under Emscripten, and 1.6.0 prepended AVX2 to that list, pushing SSE2 out of range. Left alone, that silently compiles every *_sse2.c to nothing — most of the SIMD win — and breaks enc_sse41.c, which needs the inline helpers in common_sse2.h. The SIMD build now asserts its extension set by hand rather than leaving it to probing; wasm is a fixed target, so there's nothing to probe for.

Threads

WEBP_USE_THREAD=0 says directly what CMAKE_DISABLE_FIND_PACKAGE_Threads=1 was arranging indirectly by making libwebp's find_package(Threads) fail. With 1.6.0, libwebp no longer reaches that call, so the old flag had become an unused-variable warning on every configure. The decoder wasm is byte-identical across the swap, which is the check that the two flags land in the same place.

Emscripten 4.0.16

4.0.16 is the first emsdk image published for arm64, so it's the first that doesn't run under QEMU on Apple silicon, and libwebp has carried an emcc >= 3.1.27 fix since 1.3.1.

It needs one change in the shared tools/cpp.Dockerfile: 4.x rejects TEXTDECODER=0 outright (#error "TEXTDECODER must be either 1 or 2"), during the stdlib warm-up, so nothing compiles at all. TEXTDECODER=1 uses TextDecoder where it exists and falls back to plain JS, so the property the flag was set for is preserved. Other codecs pin their own EMSDK_VERSION and are unaffected until they're next rebuilt.

One rough edge: tools/build-cpp.sh tags the image jsquash-cpp-build regardless of toolchain, so now that codecs pin different Emscripten versions, building two in a row rebuilds the image each time. #111 fixes that by tagging per toolchain — worth landing first if you're taking both, but this PR doesn't depend on it.

Measurements

1024x768, median of 5 runs, new modules vs the ones they replace:

scalar SIMD
encode q75 83.7 → 83.0 ms 68.9 → 67.9 ms
encode q90 130.7 → 132.6 ms 98.3 → 98.7 ms
encode lossless 284.1 → 267.5 ms 254.1 → 233.1 ms
decode lossy 8.7 → 8.5 ms —
decode lossless 22.6 → 21.2 ms —

Lossy output is byte-for-byte the same size at the same PSNR, so nothing is bought with quality. Sharp YUV is 0.7% larger for 0.06 dB more PSNR, which is the sharper conversion from 1.2.3. As the issue predicted, the headline is decode safety rather than a size win: CVE-2023-4863 (lossless decoder heap OOB write), CVE-2023-1999 (lossless encoder UAF/double-free), and everything since.

Module sizes: encoder 281,261 → 293,535 bytes, SIMD encoder 345,584 → 340,202, decoder 137,960 → 144,617.

qmin / qmax

frame_enc.c clamps quality into [qmin, qmax] on every lossy encode. The fields were never bound, so the glue hardcoded config.qmax = 100 to stop the zero-initialised struct from pinning every encode to quality 0 — that's what the "allow quality to go higher than 0" line was for. Both are bound now, defaulted to [0, 100] in meta.ts, and the hardcode is gone.

thread_level was in EncodeOptions and defaultOptions but not in the value_object, so the field was silently dropped. Bound too — a no-op while the modules are built without pthreads, but the options list and the struct now agree.

One caveat. embind rejects a value_object with a missing field (TypeError: Missing field: "qmin") rather than defaulting it, so anyone driving the codec module directly with a hand-assembled config has to carry the two new fields. encode() merges defaultOptions, so the package API is unaffected — but EncodeOptions does gain two required properties, which TypeScript will flag for anyone who writes the config out in full. Happy to drop the second commit if you'd rather ship the codec bump on its own.

Testing

npm test in test/: 50 passed, including a new one that checks qmax actually caps quality (it fails against the old module, where the field is ignored). Also verified by hand against the previous modules: version(), lossy/lossless/sharp-YUV round-trips, PSNR and output size.

No CHANGELOG entry or version bump here — say the word and I'll add them.

🤖 Generated with Claude Code

chriskellet and others added 2 commits September 2, 2026 11:50
The pin was a bare commit hash from 24 Nov 2020, between v1.1.0 and
v1.2.0. Move it to the v1.6.0 release tag so the version is legible from
the Makefile and cannot drift from the READMEs again, and rebuild all
three modules: `version()` went from 0x010100 to 0x010600.

Emscripten moves from the script's 2.0.34 default to 4.0.16. 4.0.16 is
the first emsdk image published for arm64, so it is the first that does
not run under QEMU on Apple silicon, and libwebp has carried an
emcc >= 3.1.27 fix since 1.3.1. That bump needs TEXTDECODER=1: 4.x
rejects TEXTDECODER=0 outright ("TEXTDECODER must be either 1 or 2") and
does so during the Dockerfile's stdlib warm-up, so nothing compiles at
all. TEXTDECODER=1 uses TextDecoder where it exists and falls back to
plain JS, so the property the flag was set for is preserved. Other
codecs still pin their own EMSDK_VERSION and are unaffected until they
are next rebuilt.

Three things in the newer libwebp needed handling:

- Sharp YUV ships as its own libsharpyuv.a since 1.2.1, and
  picture_csp_enc.c references it unconditionally, so it has to be on
  the encoder link line. The decoder does not pull those symbols in.
- 1.6.0 added AVX2 lossless paths. Emscripten emulates 256-bit
  intrinsics as pairs of 128-bit wasm SIMD ops, so they cost binary size
  without buying throughput, and they do not compile: the sources pass
  __m256i* into intrinsics Emscripten declares as taking __m256i_u*.
  Masked off with -U__AVX2__.
- Masking AVX2 is not enough on its own. cpu.cmake stops probing at the
  third entry of its extension list under Emscripten, and 1.6.0
  prepended AVX2 to that list, which pushed SSE2 out of range. Left
  alone that silently compiles every *_sse2.c to nothing - most of the
  SIMD win - and breaks enc_sse41.c, which needs the inline helpers in
  common_sse2.h. SSE2 is now asserted explicitly.

WEBP_USE_THREAD=0 replaces CMAKE_DISABLE_FIND_PACKAGE_Threads=1, which
reached the same end state indirectly by making libwebp's
find_package(Threads) fail. libwebp no longer even reaches that call, so
the old flag had become an unused-variable warning on every configure.
The decoder wasm is byte-identical across the swap.

Measured at 1024x768, median of 5 runs, against the modules this
replaces:

  encode q75    scalar  83.7 -> 83.0 ms    SIMD  68.9 -> 67.9 ms
  encode q90    scalar 130.7 -> 132.6 ms   SIMD  98.3 -> 98.7 ms
  encode lossless scalar 284.1 -> 267.5 ms SIMD 254.1 -> 233.1 ms
  decode lossy          8.7 -> 8.5 ms
  decode lossless      22.6 -> 21.2 ms

Lossy output is byte-for-byte the same size at the same PSNR, so nothing
is bought with quality. Sharp YUV is 0.7% larger for 0.06 dB more PSNR,
which is the sharper conversion from 1.2.3. Module size: encoder
281,261 -> 293,351 bytes, SIMD encoder 345,584 -> 340,019, decoder
137,960 -> 144,617.

49 integration tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
libwebp 1.2.0 added a permissible quality range to WebPConfig, and
frame_enc.c clamps `quality` into it on every lossy encode. The fields
were never bound, so the glue hardcoded `config.qmax = 100` to stop the
zero-initialised struct from pinning every encode to quality 0 - the
"allow quality to go higher than 0" line. Bind both fields, default them
to [0, 100] in meta.ts, and drop the hardcode: the range now arrives
from the caller like every other option.

`thread_level` was already in EncodeOptions and defaultOptions but was
missing from the value_object, so that field was silently dropped on its
way to the encoder. Bound as well. It is a no-op while the modules are
built without pthreads, but the options and the struct now agree, and
the binding list mirrors struct WebPConfig field for field.

One caveat for anyone driving the codec module directly rather than
through encode(): embind rejects a value_object with a missing field
("Missing field: qmin"), so a hand-assembled config has to carry the two
new fields. encode() merges defaultOptions, so the package API is
unaffected - and EncodeOptions gains two required properties, which will
show up in TypeScript for anyone who writes the config out in full.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Upgrade @jsquash/webp codec from libwebp ~1.1.x (Nov 2020) to v1.6.0

2 participants